fq_server/settings.py (1)

74-87: Consider accepting numeric boolean values (0/1).

The boolean validator strictly accepts only bool or "true"/"false" strings. Some deployment tools and shell scripts may pass 1 or 0 as boolean values. Consider whether this strictness is intentional or if numeric booleans should be supported.

♻️ Optional: Support numeric boolean values

     `@field_validator`("enable_requeue_script", "redis_clustered", mode="before")
     `@classmethod`
     def validate_boolean_env(cls, value: bool | str) -> bool:
         if isinstance(value, bool):
             return value
 
+        if isinstance(value, int):
+            if value == 1:
+                return True
+            if value == 0:
+                return False
+
         if isinstance(value, str):
             normalized = value.strip().lower()
             if normalized == "true":
                 return True
             if normalized == "false":
                 return False
+            if normalized in ("1", "0"):
+                return normalized == "1"
 
-        raise ValueError("Use either 'true' or 'false'.")
+        raise ValueError("Use 'true', 'false', '1', or '0'.")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@fq_server/settings.py` around lines 74 - 87, The validate_boolean_env
validator currently only accepts bool or "true"/"false" strings; update
validate_boolean_env (the `@field_validator` for "enable_requeue_script" and
"redis_clustered") to also accept numeric booleans by handling int values 0/1
and string "0"/"1" (and any whitespace) — convert 1/"1"/True to True and
0/"0"/False to False, keep existing handling for bool and "true"/"false", and
preserve the ValueError fallback message.

README.md (2)

65-67: Same redundancy as in getting started guide.

The PORT=8080 environment variable is redundant here since --port 8080 is passed explicitly to uvicorn.

📝 Suggested simplification

-PORT=8080 \
 FQ_REDIS_HOST=127.0.0.1 \
 uv run uvicorn asgi:app --host 0.0.0.0 --port 8080

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 65 - 67, The README shows setting PORT=8080 while
also passing --port 8080 to the uvicorn command; remove the redundant PORT=8080
environment variable to avoid duplication. Update the section so only necessary
env vars (e.g., FQ_REDIS_HOST) are exported and the uvicorn invocation remains
as "uv run uvicorn asgi:app --host 0.0.0.0 --port 8080" (or, alternatively, keep
PORT and drop the explicit --port flag) so that either the PORT env var or the
--port argument is used, not both.

---

50-50: Clarify that PORT is not an application setting.

PORT is listed alongside FQ_* variables in the configuration table, but it's not read by QueueServerSettings. It's a convention for container runtimes and the uvicorn CLI. This could mislead users into thinking the application validates it.

Consider either:

1. Moving PORT to a separate "Runtime" section with a note that it's for uvicorn/container use.
2. Adding a clarifying note that PORT is not validated by the application.

📝 Suggested clarification

 | `FQ_REDIS_UNIX_SOCKET_PATH` | `/tmp/redis.sock` | Redis socket path when `FQ_REDIS_CONN_TYPE=unix_sock`. |
-| `PORT` | `8300` | Uvicorn port used by the container and local examples. |
+
+**Runtime settings (not validated by the application):**
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PORT` | — | Port for uvicorn. Pass via `--port` flag or container runtime. |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 50, Move or annotate the `PORT` entry so readers know it's
a runtime/uvicorn/container convention and not an application-configured value;
specifically update the README table row that currently lists `PORT` next to
`FQ_*` vars by either (a) moving `PORT` into a new "Runtime" or
"Container/runtime" section with a short note that it is used by
uvicorn/container runtimes, or (b) adding a one-line clarification next to the
`PORT` row stating that `PORT` is not read or validated by the application
(e.g., QueueServerSettings) but is used by the uvicorn CLI/container
environment.

docs/gettingstarted.rst (1)

19-21: Redundant PORT environment variable.

The PORT=8080 environment variable on line 19 is redundant since uvicorn is invoked with the explicit --port 8080 flag. Additionally, PORT is not read by QueueServerSettings (per fq_server/settings.py); it's only a convention for some container runtimes.

Consider simplifying:

📝 Suggested change

-    PORT=8080 \
     FQ_REDIS_HOST=127.0.0.1 \
     uv run uvicorn asgi:app --host 0.0.0.0 --port 8080

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/gettingstarted.rst` around lines 19 - 21, Remove the redundant PORT=8080
environment variable and its assignment from the startup example because uvicorn
is already started with an explicit --port 8080 flag; update the example to only
set runtime-relevant variables (e.g., FQ_REDIS_HOST) and keep the uvicorn
invocation (uv run uvicorn asgi:app --host 0.0.0.0 --port 8080); note that
QueueServerSettings does not read PORT so no code changes to QueueServerSettings
are needed—just remove the PORT line from the docs.

pyproject.toml (1)

8-8: Git-pinned dependency may impact reproducibility and installation.

Pinning to a Git tag (@v1.0.0) is acceptable when the package isn't on PyPI, but be aware:

1. Users behind firewalls may have issues accessing GitHub.
2. Git dependencies aren't cached by pip the same way as PyPI packages.
3. If the tag is ever moved/deleted upstream, builds will break.

Consider publishing flowdacity-queue to PyPI when feasible for broader compatibility.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pyproject.toml` at line 8, The dependency line using a Git tag for
"flowdacity-queue" can break reproducibility and installations; update the
pyproject entry for flowdacity-queue to a PyPI release (e.g., replace the git+
URL with flowdacity-queue==<version> once published) or, if publishing to PyPI
isn’t possible yet, pin to an immutable commit hash
(git+https://...@<commit-sha>) and add a short comment in pyproject explaining
the Git fallback and firewall/GitHub access limitations so maintainers know why
it’s needed.

fq_server/server.py (1)

317-323: Consider narrowing exception handling for clarity.

The broad Exception catch handles both JSON parsing and missing "interval" key. While functional, explicitly catching (json.JSONDecodeError, KeyError) would make the intent clearer and avoid accidentally swallowing unexpected errors.

♻️ Optional refinement

         try:
             raw_body = await request.body()
             body: JSONDict = json.loads(raw_body or b"{}")
             interval = body["interval"]
-        except Exception as e:
+        except (json.JSONDecodeError, KeyError) as e:
             response["message"] = str(e)
             return JSONResponse(response, status_code=400)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@fq_server/server.py` around lines 317 - 323, The current broad except
Exception in the request body parsing swallows unrelated errors; narrow it to
explicitly catch json.JSONDecodeError and KeyError when calling request.body(),
json.loads(raw_body or b"{}") and accessing body["interval"], then set
response["message"]=str(e) and return JSONResponse(response, status_code=400)
inside that specific except block so other exceptions bubble up.

docs/faqs.rst (1)

36-57: Worker example could benefit from error handling for network failures.

The example handles 200 and 404 status codes but will raise RuntimeError for all other responses, including transient network errors (connection timeouts, etc.) which httpx raises as exceptions before a response is received.

Consider adding a brief note about production workers needing retry logic for transient failures, or wrap the example in a try/except:

📝 Suggested enhancement

     with httpx.Client(base_url="http://127.0.0.1:8080") as client:
         while True:
-            response = client.get("/dequeue/sms/")
+            try:
+                response = client.get("/dequeue/sms/")
+            except httpx.RequestError:
+                time.sleep(1)
+                continue

             if response.status_code == 200:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/faqs.rst` around lines 36 - 57, The example loop using httpx.Client
currently only handles HTTP status codes and raises RuntimeError for other
responses but does not catch httpx network exceptions; wrap the dequeue/finish
calls (the client.get and client.post calls inside the while True) in a
try/except that catches httpx.RequestError (and optionally
httpx.TimeoutException) to implement a simple retry/backoff (e.g., time.sleep
before retry) and log or continue on transient failures, or add a short note
next to the httpx.Client example advising production workers must add retry
logic and error handling around client.get/client.post and avoid letting network
exceptions crash the worker.

tests/test_routes.py (1)

548-556: Await the disabled requeue task so this test catches regressions.

done() only tells us the coroutine finished. If requeue_with_lock() starts raising immediately, this still passes. Awaiting the task and restoring the flag in finally makes the assertion reliable.

Suggested test hardening

-        server.config["fq"]["enable_requeue_script"] = False
-        requeue_task = asyncio.create_task(server.requeue_with_lock())
-
-        # Should return immediately (task completes)
-        await asyncio.sleep(0.1)
-
-        # Task should be done (returned, not cancelled)
-        self.assertTrue(requeue_task.done())
-        server.config["fq"]["enable_requeue_script"] = True
+        server.config["fq"]["enable_requeue_script"] = False
+        try:
+            requeue_task = asyncio.create_task(server.requeue_with_lock())
+
+            # Should return immediately (task completes)
+            await asyncio.sleep(0.1)
+
+            # Task should be done and should not have failed
+            self.assertTrue(requeue_task.done())
+            await requeue_task
+        finally:
+            server.config["fq"]["enable_requeue_script"] = True

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_routes.py` around lines 548 - 556, Await the created requeue task
instead of only checking requeue_task.done() and ensure the config flag
server.config["fq"]["enable_requeue_script"] is restored in a finally block;
specifically, after creating requeue_task via
asyncio.create_task(server.requeue_with_lock()), await requeue_task (to surface
any immediate exceptions from requeue_with_lock()) and move the flag reset
(server.config["fq"]["enable_requeue_script"] = True) into a finally clause so
the test reliably fails on regressions and always restores state.

README.md (1)

51-51: ⚠️ Potential issue | 🟡 Minor

Clarify that PORT is a launcher variable and use it in the command.

Line 51 still reads like app-level validated config, and Lines 66-68 export PORT but don’t consume it.

📘 Suggested doc patch

-| `PORT` | `8300` | Uvicorn port used by the container and local examples. |
+| `PORT` | `8300` | Launcher/Uvicorn variable for startup commands; not read by `QueueServerSettings`. |
...
 PORT=8300 \
 REDIS_HOST=127.0.0.1 \
-uv run uvicorn asgi:app --host 0.0.0.0 --port 8300
+uv run uvicorn asgi:app --host 0.0.0.0 --port "$PORT"

Also applies to: 66-69

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 51, The README incorrectly presents PORT as an app-level
validated config; update the docs to state PORT is a launcher/environment
variable (not validated by the app) and demonstrate using it in the start
command (e.g., show export PORT=8300 then use it when launching Uvicorn) so the
examples at the earlier table row (`PORT`) and the export block (lines showing
export PORT) clearly indicate it is consumed by the launcher; update the
descriptive text for the `PORT` table entry and the example start command to
reference the `PORT` environment variable explicitly.

tests/test_routes.py (1)

548-556: Make test_requeue_with_lock_disabled deterministic and restore config in finally.

Current sleep-based completion check is timing-sensitive, and config restoration should be guarded even on assertion failure.

🧪 Suggested test hardening

-        server.config["fq"]["enable_requeue_script"] = False
-        requeue_task = asyncio.create_task(server.requeue_with_lock())
-
-        # Should return immediately (task completes)
-        await asyncio.sleep(0.1)
-
-        # Task should be done (returned, not cancelled)
-        self.assertTrue(requeue_task.done())
-        server.config["fq"]["enable_requeue_script"] = True
+        original = server.config["fq"]["enable_requeue_script"]
+        try:
+            server.config["fq"]["enable_requeue_script"] = False
+            await asyncio.wait_for(server.requeue_with_lock(), timeout=0.5)
+        finally:
+            server.config["fq"]["enable_requeue_script"] = original

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_routes.py` around lines 548 - 556, Replace the timing-sensitive
sleep+assert with a deterministic await using asyncio.wait_for on requeue_task
(e.g., await asyncio.wait_for(requeue_task, timeout=1)) to ensure the task
completes within a bounded time and then assert requeue_task.done() and not
requeue_task.cancelled(); also wrap the test body in a try/finally and restore
server.config["fq"]["enable_requeue_script"] = True in the finally block so the
config is always restored even if assertions fail; target the requeue_task
creation and server.requeue_with_lock() call in this change.

README.md (1)

49-49: ⚠️ Potential issue | 🟡 Minor

PORT is still documented as an app setting, but the app settings model does not read it.

Line 49 places PORT in the validated config table, and Lines 64-67 set PORT while still hardcoding --port 8300. This is misleading: PORT is a launcher/runtime variable, not a QueueServerSettings field.

Suggested doc fix

-| `PORT` | `8300` | Uvicorn port used by the container and local examples. |
+| `PORT` | `8300` | Launcher/Uvicorn port variable; not read by `QueueServerSettings` or `asgi.py`. |

-PORT=8300 \
-REDIS_HOST=127.0.0.1 \
-uv run uvicorn asgi:app --host 0.0.0.0 --port 8300
+export PORT=8300
+export REDIS_HOST=127.0.0.1
+uv run uvicorn asgi:app --host 0.0.0.0 --port "$PORT"

Also applies to: 64-67

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 49, The README incorrectly lists PORT as a validated app
setting and shows the launcher hardcoding --port 8300; remove PORT from the
QueueServerSettings/validated config table and instead document PORT as a
launcher/runtime environment variable (or CLI option) used by the
container/launcher, and update the example run command (the section around the
hardcoded "--port 8300") to either reference the PORT env var or show how to
pass it from the launcher/CLI; refer to the PORT name and the
QueueServerSettings concept in the README so the change clearly separates
runtime launcher configuration from the app settings model.

README.md (1)

9-9: Heading style is inconsistent with markdownlint MD003.

Lines 9, 14, 53, and 69 use ATX headings while this doc is otherwise setext-oriented per lint expectations. Please normalize heading style to satisfy the configured markdown rule.

Also applies to: 14-14, 53-53, 69-69

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 9, The README uses ATX-style headings (e.g., "##
Prerequisites") that conflict with the document's setext-oriented style per
markdownlint MD003; update the ATX headings ("Prerequisites" and the other ATX
headings flagged in the comment) to setext-style headings by replacing the
leading "##" with an underline of === (for level 1) or --- (for level 2)
matching the heading text length so the heading style is normalized across the
file and satisfies MD003.

docs/conf.py (1)

16-19: Consider updating the copyright year.

The copyright year is set to 2025. If this reflects when the project started, it's fine. Otherwise, consider updating to 2026 or using a range like "2025-2026, Flowdacity Development Team".

Note: The Ruff warning about copyright shadowing a Python builtin is a false positive—copyright is a standard Sphinx configuration variable required by the framework.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/conf.py` around lines 16 - 19, Update the Sphinx config value named
copyright in docs/conf.py to the correct year or a year range (for example
change the string "2025, Flowdacity Development Team" to "2026, Flowdacity
Development Team" or "2025-2026, Flowdacity Development Team") so the project
metadata reflects the current copyright period; leave the variable name as-is
since it is the Sphinx-required configuration key.

fq_server/server.py (1)

80-96: ⚠️ Potential issue | 🟠 Major

Requeue loop still vulnerable to non-LockError exceptions.

The None check is a good improvement, but redis.lock() and the async context manager can raise other exceptions (e.g., ConnectionError, TimeoutError, RedisError) that would terminate the background task permanently. Only LockError is caught.

Consider adding a broader exception handler to keep the loop running:

Suggested hardening

             except LockError:
                 # the lock wasn't acquired within specified time
                 logger.debug("Requeue lock is already held by another worker")
+            except Exception:
+                logger.exception("Requeue loop encountered an error; will retry")
             finally:
                 await asyncio.sleep(job_requeue_interval / 1000.0)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@fq_server/server.py` around lines 80 - 96, The requeue loop around
redis.lock("fq-requeue-lock-key") only catches LockError and will exit on other
redis/connection exceptions; update the while True loop in server.py (the block
using self.queue.redis_client(), redis.lock(...), async with, and await
self.queue.requeue()) to catch broader exceptions (e.g., Exception or specific
Redis/Connection/Timeout errors) separate from LockError so the background task
continues running: keep the current LockError handling for lock contention, log
and swallow other transient errors from redis.lock() and the async context
manager (including connection/timeout/Redis errors) with appropriate
logger.exception/ logger.error messages, but do not let them propagate and stop
the loop; ensure the finally still awaits asyncio.sleep(job_requeue_interval /
1000.0).

docs/conf.py (2)

19-25: copyright shadows Python builtin (Ruff A001).

This is the standard Sphinx configuration variable name, so the shadowing is expected and harmless in this context. You can silence the linter with a # noqa: A001 comment if the project enforces zero Ruff warnings.

-copyright = "2025, Flowdacity Development Team"
+copyright = "2025, Flowdacity Development Team"  # noqa: A001

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/conf.py` around lines 19 - 25, The linter flags that the variable name
copyright shadows a Python builtin; suppress this harmless warning by adding a
noqa comment to that assignment line: update the assignment to the copyright
variable in docs/conf.py (the line that currently reads `copyright = "2025,
Flowdacity Development Team"`) to append `# noqa: A001` so Ruff ignores the
shadowing while keeping the Sphinx config name intact.

---

22-25: Consider using tomllib.load() with a file handle.

Using tomllib.load() with a binary file handle is slightly more memory-efficient and idiomatic than tomllib.loads() with read_text().

♻️ Suggested improvement

 project_root = Path(__file__).resolve().parents[1]
-release = tomllib.loads((project_root / "pyproject.toml").read_text(encoding="utf-8"))[
-    "project"
-]["version"]
+with (project_root / "pyproject.toml").open("rb") as f:
+    release = tomllib.load(f)["project"]["version"]
 version = release

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/conf.py` around lines 22 - 25, The current code uses tomllib.loads on
the entire file text; instead open the pyproject.toml file as a binary file
handle and call tomllib.load to parse it (replace the use of
tomllib.loads((project_root / "pyproject.toml").read_text(...)) with opening
project_root / "pyproject.toml" in "rb" and passing that handle to
tomllib.load), then extract ["project"]["version"] into the release variable and
set version = release; keep references to release and project_root as-is.